Autogenerated HTML docs for v1.7.1-331-ga5080
diff --git a/cmds-mainporcelain.txt b/cmds-mainporcelain.txt index a0f8470..10dfc24 100644 --- a/cmds-mainporcelain.txt +++ b/cmds-mainporcelain.txt
@@ -68,7 +68,7 @@ Move or rename a file, a directory, or a symlink. linkgit:git-notes[1]:: - Add/inspect object notes. + Add or inspect object notes. linkgit:git-pull[1]:: Fetch from and merge with another repository or a local branch.
diff --git a/config.txt b/config.txt index 85f763c..95cf73c 100644 --- a/config.txt +++ b/config.txt
@@ -520,18 +520,12 @@ core.notesRef:: When showing commit messages, also show notes which are stored in - the given ref. This ref is expected to contain files named - after the full SHA-1 of the commit they annotate. The ref - must be fully qualified. + the given ref. The ref must be fully qualified. If the given + ref does not exist, it is not an error but means that no + notes should be printed. + -If such a file exists in the given ref, the referenced blob is read, and -appended to the commit message, separated by a "Notes (<refname>):" -line (shortened to "Notes:" in the case of "refs/notes/commits"). If the -given ref itself does not exist, it is not an error, but means that no -notes should be printed. -+ -This setting defaults to "refs/notes/commits", and can be overridden by -the `GIT_NOTES_REF` environment variable. +This setting defaults to "refs/notes/commits", and it can be overridden by +the 'GIT_NOTES_REF' environment variable. See linkgit:git-notes[1]. core.sparseCheckout:: Enable "sparse checkout" feature. See section "Sparse checkout" in @@ -1481,6 +1475,16 @@ it takes precedence over this option. To disable pagination for all commands, set `core.pager` or `GIT_PAGER` to `cat`. +pretty.<name>:: + Alias for a --pretty= format string, as specified in + linkgit:git-log[1]. Any aliases defined here can be used just + as the built-in pretty formats could. For example, + running `git config pretty.changelog "format:{asterisk} %H %s"` + would cause the invocation `git log --pretty=changelog` + to be equivalent to running `git log "--pretty=format:{asterisk} %H %s"`. + Note that an alias with the same name as a built-in format + will be silently ignored. + pull.octopus:: The default merge strategy to use when pulling multiple branches at once. diff --git a/diff-options.txt b/diff-options.txt index 0d89aaa..e745a3c 100644 --- a/diff-options.txt +++ b/diff-options.txt
@@ -210,7 +210,14 @@ Break complete rewrite changes into pairs of delete and create. -M:: +ifndef::git-log[] Detect renames. +endif::git-log[] +ifdef::git-log[] + If generating diffs, detect and report renames for each commit. + For following files across renames while traversing history, see + `--follow`. +endif::git-log[] -C:: Detect copies as well as renames. See also `--find-copies-harder`.
diff --git a/git-add.html b/git-add.html index faf55bc..2b9529f 100644 --- a/git-add.html +++ b/git-add.html
@@ -671,9 +671,9 @@ <div class="content"> <pre><tt>y - stage this hunk n - do not stage this hunk -q - quit, do not stage this hunk nor any of the remaining ones -a - stage this and all the remaining hunks in the file -d - do not stage this hunk nor any of the remaining hunks in the file +q - quit; do not stage this hunk nor any of the remaining ones +a - stage this hunk and all later hunks in the file +d - do not stage this hunk nor any of the later hunks in the file g - select a hunk to go to / - search for a hunk matching the given regex j - leave this hunk undecided, see next undecided hunk @@ -721,7 +721,7 @@ </div> <div id="footer"> <div id="footer-text"> -Last updated 2010-04-24 02:55:46 UTC +Last updated 2010-06-13 19:56:31 UTC </div> </div> </body>
diff --git a/git-add.txt b/git-add.txt index 51cbeb7..74741a4 100644 --- a/git-add.txt +++ b/git-add.txt
@@ -266,9 +266,9 @@ y - stage this hunk n - do not stage this hunk - q - quit, do not stage this hunk nor any of the remaining ones - a - stage this and all the remaining hunks in the file - d - do not stage this hunk nor any of the remaining hunks in the file + q - quit; do not stage this hunk nor any of the remaining ones + a - stage this hunk and all later hunks in the file + d - do not stage this hunk nor any of the later hunks in the file g - select a hunk to go to / - search for a hunk matching the given regex j - leave this hunk undecided, see next undecided hunk
diff --git a/git-config.html b/git-config.html index 3ae1cfe..217602c 100644 --- a/git-config.html +++ b/git-config.html
@@ -1493,17 +1493,12 @@ <dd> <p> When showing commit messages, also show notes which are stored in - the given ref. This ref is expected to contain files named - after the full SHA-1 of the commit they annotate. The ref - must be fully qualified. + the given ref. The ref must be fully qualified. If the given + ref does not exist, it is not an error but means that no + notes should be printed. </p> -<div class="para"><p>If such a file exists in the given ref, the referenced blob is read, and -appended to the commit message, separated by a "Notes (<refname>):" -line (shortened to "Notes:" in the case of "refs/notes/commits"). If the -given ref itself does not exist, it is not an error, but means that no -notes should be printed.</p></div> -<div class="para"><p>This setting defaults to "refs/notes/commits", and can be overridden by -the <tt>GIT_NOTES_REF</tt> environment variable.</p></div> +<div class="para"><p>This setting defaults to "refs/notes/commits", and it can be overridden by +the <em>GIT_NOTES_REF</em> environment variable. See <a href="git-notes.html">git-notes(1)</a>.</p></div> </dd> <dt> core.sparseCheckout @@ -3326,6 +3321,21 @@ </p> </dd> <dt> +pretty.<name> +</dt> +<dd> +<p> + Alias for a --pretty= format string, as specified in + <a href="git-log.html">git-log(1)</a>. Any aliases defined here can be used just + as the built-in pretty formats could. For example, + running <tt>git config pretty.changelog "format:* %H %s"</tt> + would cause the invocation <tt>git log --pretty=changelog</tt> + to be equivalent to running <tt>git log "--pretty=format:* %H %s"</tt>. + Note that an alias with the same name as a built-in format + will be silently ignored. +</p> +</dd> +<dt> pull.octopus </dt> <dd> @@ -3916,7 +3926,7 @@ </div> <div id="footer"> <div id="footer-text"> -Last updated 2010-06-01 05:05:55 UTC +Last updated 2010-06-13 19:56:31 UTC </div> </div> </body>
diff --git a/git-cvsserver.html b/git-cvsserver.html index 136b241..0eb80de 100644 --- a/git-cvsserver.html +++ b/git-cvsserver.html
@@ -411,8 +411,6 @@ </div> <h2 id="_limitations">LIMITATIONS</h2> <div class="sectionbody"> -<div class="para"><p>Currently cvsserver works over SSH connections for read/write clients, and -over pserver for anonymous CVS access.</p></div> <div class="para"><p>CVS clients cannot tag, branch or perform GIT merges.</p></div> <div class="para"><p><em>git-cvsserver</em> maps GIT branches to CVS modules. This is very different from what most CVS users would expect since in CVS modules usually represent @@ -423,7 +421,7 @@ <div class="olist"><ol> <li> <p> -If you are going to offer anonymous CVS access via pserver, add a line in +If you are going to offer CVS access via pserver, add a line in /etc/inetd.conf like </p> <div class="listingblock"> @@ -440,6 +438,37 @@ <pre><tt> cvspserver stream tcp nowait nobody /usr/bin/git-cvsserver git-cvsserver pserver </tt></pre> </div></div> +<div class="para"><p>Only anonymous access is provided by pserve by default. To commit you +will have to create pserver accounts, simply add a gitcvs.authdb +setting in the config file of the repositories you want the cvsserver +to allow writes to, for example:</p></div> +<div class="listingblock"> +<div class="content"> +<pre><tt> + [gitcvs] + authdb = /etc/cvsserver/passwd +</tt></pre> +</div></div> +<div class="para"><p>The format of these files is username followed by the crypted password, +for example:</p></div> +<div class="listingblock"> +<div class="content"> +<pre><tt> myuser:$1Oyx5r9mdGZ2 + myuser:$1$BA)@$vbnMJMDym7tA32AamXrm./</tt></pre> +</div></div> +<div class="para"><p>You can use the <em>htpasswd</em> facility that comes with Apache to make these +files, but Apache's MD5 crypt method differs from the one used by most C +library's crypt() function, so don't use the -m option.</p></div> +<div class="para"><p>Alternatively you can produce the password with perl's crypt() operator:</p></div> +<div class="listingblock"> +<div class="content"> +<pre><tt> perl -e 'my ($user, $pass) = @ARGV; printf "%s:%s\n", $user, crypt($user, $pass)' $USER password</tt></pre> +</div></div> +<div class="para"><p>Then provide your password via the pserver method, for example:</p></div> +<div class="listingblock"> +<div class="content"> +<pre><tt> cvs -d:pserver:someuser:somepassword <at> server/path/repo.git co <HEAD_name></tt></pre> +</div></div> <div class="para"><p>No special setup is needed for SSH access, other than having GIT tools in the PATH. If you have clients that do not accept the CVS_SERVER environment variable, you can rename <em>git-cvsserver</em> to <tt>cvs</tt>.</p></div> @@ -806,7 +835,7 @@ </div> <div id="footer"> <div id="footer-text"> -Last updated 2010-04-24 02:55:51 UTC +Last updated 2010-06-13 19:56:32 UTC </div> </div> </body>
diff --git a/git-cvsserver.txt b/git-cvsserver.txt index dbb053e..c27ca43 100644 --- a/git-cvsserver.txt +++ b/git-cvsserver.txt
@@ -72,9 +72,6 @@ LIMITATIONS ----------- -Currently cvsserver works over SSH connections for read/write clients, and -over pserver for anonymous CVS access. - CVS clients cannot tag, branch or perform GIT merges. 'git-cvsserver' maps GIT branches to CVS modules. This is very different @@ -84,7 +81,7 @@ INSTALLATION ------------ -1. If you are going to offer anonymous CVS access via pserver, add a line in +1. If you are going to offer CVS access via pserver, add a line in /etc/inetd.conf like + -- @@ -101,6 +98,38 @@ cvspserver stream tcp nowait nobody /usr/bin/git-cvsserver git-cvsserver pserver ------ + +Only anonymous access is provided by pserve by default. To commit you +will have to create pserver accounts, simply add a gitcvs.authdb +setting in the config file of the repositories you want the cvsserver +to allow writes to, for example: + +------ + + [gitcvs] + authdb = /etc/cvsserver/passwd + +------ +The format of these files is username followed by the crypted password, +for example: + +------ + myuser:$1Oyx5r9mdGZ2 + myuser:$1$BA)@$vbnMJMDym7tA32AamXrm./ +------ +You can use the 'htpasswd' facility that comes with Apache to make these +files, but Apache's MD5 crypt method differs from the one used by most C +library's crypt() function, so don't use the -m option. + +Alternatively you can produce the password with perl's crypt() operator: +----- + perl -e 'my ($user, $pass) = @ARGV; printf "%s:%s\n", $user, crypt($user, $pass)' $USER password +----- + +Then provide your password via the pserver method, for example: +------ + cvs -d:pserver:someuser:somepassword <at> server/path/repo.git co <HEAD_name> +------ No special setup is needed for SSH access, other than having GIT tools in the PATH. If you have clients that do not accept the CVS_SERVER environment variable, you can rename 'git-cvsserver' to `cvs`.
diff --git a/git-diff-files.html b/git-diff-files.html index 5bd3e40..3b88214 100644 --- a/git-diff-files.html +++ b/git-diff-files.html
@@ -1498,7 +1498,7 @@ </div> <div id="footer"> <div id="footer-text"> -Last updated 2010-05-21 14:57:15 UTC +Last updated 2010-06-13 19:56:32 UTC </div> </div> </body>
diff --git a/git-diff-index.html b/git-diff-index.html index d9a0f8f..f2084e7 100644 --- a/git-diff-index.html +++ b/git-diff-index.html
@@ -1576,7 +1576,7 @@ </div> <div id="footer"> <div id="footer-text"> -Last updated 2010-05-21 14:57:16 UTC +Last updated 2010-06-13 19:56:33 UTC </div> </div> </body>
diff --git a/git-diff-tree.html b/git-diff-tree.html index 9253d21..672c29d 100644 --- a/git-diff-tree.html +++ b/git-diff-tree.html
@@ -1147,7 +1147,12 @@ have limited your view of history: for example, if you are only interested in changes related to a certain directory or file.</p></div> -<div class="para"><p>Here are some additional details for each format:</p></div> +<div class="para"><p>There are several built-in formats, and you can define +additional formats by setting a pretty.<name> +config option to either another format name, or a +<em>format:</em> string, as described below (see +<a href="git-config.html">git-config(1)</a>). Here are the details of the +built-in formats:</p></div> <div class="ilist"><ul> <li> <p> @@ -2142,7 +2147,7 @@ </div> <div id="footer"> <div id="footer-text"> -Last updated 2010-06-02 23:32:07 UTC +Last updated 2010-06-13 19:56:33 UTC </div> </div> </body>
diff --git a/git-diff.html b/git-diff.html index 8506169..cff2bf2 100644 --- a/git-diff.html +++ b/git-diff.html
@@ -1705,7 +1705,7 @@ </div> <div id="footer"> <div id="footer-text"> -Last updated 2010-05-21 14:57:17 UTC +Last updated 2010-06-13 19:56:34 UTC </div> </div> </body>
diff --git a/git-format-patch.html b/git-format-patch.html index ddec636..f777948 100644 --- a/git-format-patch.html +++ b/git-format-patch.html
@@ -1036,7 +1036,7 @@ </div> <div id="footer"> <div id="footer-text"> -Last updated 2010-05-21 14:57:18 UTC +Last updated 2010-06-13 19:56:34 UTC </div> </div> </body>
diff --git a/git-log.html b/git-log.html index f24b31b..0d98914 100644 --- a/git-log.html +++ b/git-log.html
@@ -667,7 +667,9 @@ </dt> <dd> <p> - Detect renames. + If generating diffs, detect and report renames for each commit. + For following files across renames while traversing history, see + <tt>--follow</tt>. </p> </dd> <dt> @@ -1917,7 +1919,12 @@ have limited your view of history: for example, if you are only interested in changes related to a certain directory or file.</p></div> -<div class="para"><p>Here are some additional details for each format:</p></div> +<div class="para"><p>There are several built-in formats, and you can define +additional formats by setting a pretty.<name> +config option to either another format name, or a +<em>format:</em> string, as described below (see +<a href="git-config.html">git-config(1)</a>). Here are the details of the +built-in formats:</p></div> <div class="ilist"><ul> <li> <p> @@ -2669,6 +2676,78 @@ object level, because re-coding to UTF-8 is not necessarily a reversible operation.</p></div> </div> +<h2 id="_configuration">Configuration</h2> +<div class="sectionbody"> +<div class="para"><p>See <a href="git-config.html">git-config(1)</a> for core variables and <a href="git-diff.html">git-diff(1)</a> +for settings related to diff generation.</p></div> +<div class="vlist"><dl> +<dt> +format.pretty +</dt> +<dd> +<p> + Default for the <tt>--format</tt> option. (See "PRETTY FORMATS" above.) + Defaults to "medium". +</p> +</dd> +<dt> +i18n.logOutputEncoding +</dt> +<dd> +<p> + Encoding to use when displaying logs. (See "Discussion", above.) + Defaults to the value of <tt>i18n.commitEncoding</tt> if set, UTF-8 + otherwise. +</p> +</dd> +<dt> +log.date +</dt> +<dd> +<p> + Default format for human-readable dates. (Compare the + <tt>--date</tt> option.) Defaults to "default", which means to write + dates like <tt>Sat May 8 19:35:34 2010 -0500</tt>. +</p> +</dd> +<dt> +log.showroot +</dt> +<dd> +<p> + If <tt>false</tt>, <em>git log</em> and related commands will not treat the + initial commit as a big creation event. Any root commits in + <tt>git log -p</tt> output would be shown without a diff attached. + The default is <tt>true</tt>. +</p> +</dd> +<dt> +mailmap.file +</dt> +<dd> +<p> + See <a href="git-shortlog.html">git-shortlog(1)</a>. +</p> +</dd> +<dt> +notes.displayRef +</dt> +<dd> +<p> + Which refs, in addition to the default set by <tt>core.notesRef</tt> + or <em>GIT_NOTES_REF</em>, to read notes from when showing commit + messages with the <em>log</em> family of commands. See + <a href="git-notes.html">git-notes(1)</a>. +</p> +<div class="para"><p>May be an unabbreviated ref name or a glob and may be specified +multiple times. A warning will be issued for refs that do not exist, +but a glob that does not match any refs is silently ignored.</p></div> +<div class="para"><p>This setting can be disabled by the <tt>--no-standard-notes</tt> option, +overridden by the <em>GIT_NOTES_DISPLAY_REF</em> environment variable, +and supplemented by the <tt>--show-notes</tt> option.</p></div> +</dd> +</dl></div> +</div> <h2 id="_author">Author</h2> <div class="sectionbody"> <div class="para"><p>Written by Linus Torvalds <torvalds@osdl.org></p></div> @@ -2683,7 +2762,7 @@ </div> <div id="footer"> <div id="footer-text"> -Last updated 2010-06-02 23:32:07 UTC +Last updated 2010-06-13 19:56:35 UTC </div> </div> </body>
diff --git a/git-log.txt b/git-log.txt index a2d55f9..0e6ff31 100644 --- a/git-log.txt +++ b/git-log.txt
@@ -133,6 +133,48 @@ include::i18n.txt[] +Configuration +------------- + +See linkgit:git-config[1] for core variables and linkgit:git-diff[1] +for settings related to diff generation. + +format.pretty:: + Default for the `--format` option. (See "PRETTY FORMATS" above.) + Defaults to "medium". + +i18n.logOutputEncoding:: + Encoding to use when displaying logs. (See "Discussion", above.) + Defaults to the value of `i18n.commitEncoding` if set, UTF-8 + otherwise. + +log.date:: + Default format for human-readable dates. (Compare the + `--date` option.) Defaults to "default", which means to write + dates like `Sat May 8 19:35:34 2010 -0500`. + +log.showroot:: + If `false`, 'git log' and related commands will not treat the + initial commit as a big creation event. Any root commits in + `git log -p` output would be shown without a diff attached. + The default is `true`. + +mailmap.file:: + See linkgit:git-shortlog[1]. + +notes.displayRef:: + Which refs, in addition to the default set by `core.notesRef` + or 'GIT_NOTES_REF', to read notes from when showing commit + messages with the 'log' family of commands. See + linkgit:git-notes[1]. ++ +May be an unabbreviated ref name or a glob and may be specified +multiple times. A warning will be issued for refs that do not exist, +but a glob that does not match any refs is silently ignored. ++ +This setting can be disabled by the `--no-standard-notes` option, +overridden by the 'GIT_NOTES_DISPLAY_REF' environment variable, +and supplemented by the `--show-notes` option. Author ------
diff --git a/git-notes.html b/git-notes.html index 779b101..b811976 100644 --- a/git-notes.html +++ b/git-notes.html
@@ -314,7 +314,7 @@ <h2>NAME</h2> <div class="sectionbody"> <p>git-notes - - Add/inspect object notes + Add or inspect object notes </p> </div> </div> @@ -328,25 +328,26 @@ <em>git notes</em> edit [<object>] <em>git notes</em> show [<object>] <em>git notes</em> remove [<object>] -<em>git notes</em> prune</div></div> +<em>git notes</em> prune [-n | -v]</div></div> </div> <h2 id="_description">DESCRIPTION</h2> <div class="sectionbody"> -<div class="para"><p>This command allows you to add/remove notes to/from objects, without -changing the objects themselves.</p></div> -<div class="para"><p>A typical use of notes is to extend a commit message without having -to change the commit itself. Such commit notes can be shown by <tt>git log</tt> -along with the original commit message. To discern these notes from the +<div class="para"><p>Adds, removes, or reads notes attached to objects, without touching +the objects themselves.</p></div> +<div class="para"><p>By default, notes are saved to and read from <tt>refs/notes/commits</tt>, but +this default can be overridden. See the OPTIONS, CONFIGURATION, and +ENVIRONMENT sections below. If this ref does not exist, it will be +quietly created when it is first needed to store a note.</p></div> +<div class="para"><p>A typical use of notes is to supplement a commit message without +changing the commit itself. Notes can be shown by <em>git log</em> along with +the original commit message. To distinguish these notes from the message stored in the commit object, the notes are indented like the message, after an unindented line saying "Notes (<refname>):" (or -"Notes:" for the default setting).</p></div> -<div class="para"><p>This command always manipulates the notes specified in "core.notesRef" -(see <a href="git-config.html">git-config(1)</a>), which can be overridden by GIT_NOTES_REF. -To change which notes are shown by <em>git-log</em>, see the -"notes.displayRef" configuration.</p></div> -<div class="para"><p>See the description of "notes.rewrite.<command>" in -<a href="git-config.html">git-config(1)</a> for a way of carrying your notes across commands -that rewrite commits.</p></div> +"Notes:" for <tt>refs/notes/commits</tt>).</p></div> +<div class="para"><p>To change which notes are shown by <em>git log</em>, see the +"notes.displayRef" configuration in <a href="git-log.html">git-log(1)</a>.</p></div> +<div class="para"><p>See the "notes.rewrite.<command>" configuration for a way to carry +notes across commands that rewrite commits.</p></div> </div> <h2 id="_subcommands">SUBCOMMANDS</h2> <div class="sectionbody"> @@ -463,6 +464,8 @@ Use the given note message (instead of prompting). If multiple <tt>-m</tt> options are given, their values are concatenated as separate paragraphs. + Lines starting with <tt>#</tt> and empty lines other than a + single line between paragraphs will be stripped out. </p> </dd> <dt> @@ -475,6 +478,8 @@ <p> Take the note message from the given file. Use <em>-</em> to read the note message from the standard input. + Lines starting with <tt>#</tt> and empty lines other than a + single line between paragraphs will be stripped out. </p> </dd> <dt> @@ -485,7 +490,8 @@ </dt> <dd> <p> - Reuse the note message from the given note object. + Take the note message from the given blob object (for + example, another note). </p> </dd> <dt> @@ -505,22 +511,197 @@ </dt> <dd> <p> - Manipulate the notes tree in <ref>. This overrides both - GIT_NOTES_REF and the "core.notesRef" configuration. The ref + Manipulate the notes tree in <ref>. This overrides + <em>GIT_NOTES_REF</em> and the "core.notesRef" configuration. The ref is taken to be in <tt>refs/notes/</tt> if it is not qualified. </p> </dd> +<dt> +-n +</dt> +<dd> +<p> + Do not remove anything; just report the object names whose notes + would be removed. +</p> +</dd> +<dt> +-v +</dt> +<dd> +<p> + Report all object names whose notes are removed. +</p> +</dd> </dl></div> </div> -<h2 id="_notes">NOTES</h2> +<h2 id="_discussion">DISCUSSION</h2> <div class="sectionbody"> +<div class="para"><p>Commit notes are blobs containing extra information about an object +(usually information to supplement a commit's message). These blobs +are taken from notes refs. A notes ref is usually a branch which +contains "files" whose paths are the object names for the objects +they describe, with some directory separators included for performance +reasons <br />[Permitted pathnames have the form +<em>ab</em><tt>/</tt><em>cd</em><tt>/</tt><em>ef</em><tt>/</tt><em>…</em><tt>/</tt><em>abcdef…</em>: a sequence of directory +names of two hexadecimal digits each followed by a filename with the +rest of the object ID.]<br />.</p></div> <div class="para"><p>Every notes change creates a new commit at the specified notes ref. You can therefore inspect the history of the notes by invoking, e.g., -<tt>git log -p notes/commits</tt>.</p></div> -<div class="para"><p>Currently the commit message only records which operation triggered -the update, and the commit authorship is determined according to the -usual rules (see <a href="git-commit.html">git-commit(1)</a>). These details may change in -the future.</p></div> +<tt>git log -p notes/commits</tt>. Currently the commit message only records +which operation triggered the update, and the commit authorship is +determined according to the usual rules (see <a href="git-commit.html">git-commit(1)</a>). +These details may change in the future.</p></div> +<div class="para"><p>It is also permitted for a notes ref to point directly to a tree +object, in which case the history of the notes can be read with +<tt>git log -p -g <refname></tt>.</p></div> +</div> +<h2 id="_examples">EXAMPLES</h2> +<div class="sectionbody"> +<div class="para"><p>You can use notes to add annotations with information that was not +available at the time a commit was written.</p></div> +<div class="listingblock"> +<div class="content"> +<pre><tt>$ git notes add -m 'Tested-by: Johannes Sixt <j6t@kdbg.org>' 72a144e2 +$ git show -s 72a144e +[...] + Signed-off-by: Junio C Hamano <gitster@pobox.com> + +Notes: + Tested-by: Johannes Sixt <j6t@kdbg.org></tt></pre> +</div></div> +<div class="para"><p>In principle, a note is a regular Git blob, and any kind of +(non-)format is accepted. You can binary-safely create notes from +arbitrary files using <em>git hash-object</em>:</p></div> +<div class="listingblock"> +<div class="content"> +<pre><tt>$ cc *.c +$ blob=$(git hash-object -w a.out) +$ git notes --ref=built add -C "$blob" HEAD</tt></pre> +</div></div> +<div class="para"><p>Of course, it doesn't make much sense to display non-text-format notes +with <em>git log</em>, so if you use such notes, you'll probably need to write +some special-purpose tools to do something useful with them.</p></div> +</div> +<h2 id="_configuration">CONFIGURATION</h2> +<div class="sectionbody"> +<div class="vlist"><dl> +<dt> +core.notesRef +</dt> +<dd> +<p> + Notes ref to read and manipulate instead of + <tt>refs/notes/commits</tt>. Must be an unabbreviated ref name. + This setting can be overridden through the environment and + command line. +</p> +</dd> +<dt> +notes.displayRef +</dt> +<dd> +<p> + Which ref (or refs, if a glob or specified more than once), in + addition to the default set by <tt>core.notesRef</tt> or + <em>GIT_NOTES_REF</em>, to read notes from when showing commit + messages with the <em>git log</em> family of commands. + This setting can be overridden on the command line or by the + <em>GIT_NOTES_DISPLAY_REF</em> environment variable. + See <a href="git-log.html">git-log(1)</a>. +</p> +</dd> +<dt> +notes.rewrite.<command> +</dt> +<dd> +<p> + When rewriting commits with <command> (currently <tt>amend</tt> or + <tt>rebase</tt>), if this variable is <tt>false</tt>, git will not copy + notes from the original to the rewritten commit. Defaults to + <tt>true</tt>. See also "<tt>notes.rewriteRef</tt>" below. +</p> +<div class="para"><p>This setting can be overridden by the <em>GIT_NOTES_REWRITE_REF</em> +environment variable.</p></div> +</dd> +<dt> +notes.rewriteMode +</dt> +<dd> +<p> + When copying notes during a rewrite, what to do if the target + commit already has a note. Must be one of <tt>overwrite</tt>, + <tt>concatenate</tt>, and <tt>ignore</tt>. Defaults to <tt>concatenate</tt>. +</p> +<div class="para"><p>This setting can be overridden with the <tt>GIT_NOTES_REWRITE_MODE</tt> +environment variable.</p></div> +</dd> +<dt> +notes.rewriteRef +</dt> +<dd> +<p> + When copying notes during a rewrite, specifies the (fully + qualified) ref whose notes should be copied. May be a glob, + in which case notes in all matching refs will be copied. You + may also specify this configuration several times. +</p> +<div class="para"><p>Does not have a default value; you must configure this variable to +enable note rewriting.</p></div> +<div class="para"><p>Can be overridden with the <em>GIT_NOTES_REWRITE_REF</em> environment variable.</p></div> +</dd> +</dl></div> +</div> +<h2 id="_environment">ENVIRONMENT</h2> +<div class="sectionbody"> +<div class="vlist"><dl> +<dt> +<em>GIT_NOTES_REF</em> +</dt> +<dd> +<p> + Which ref to manipulate notes from, instead of <tt>refs/notes/commits</tt>. + This overrides the <tt>core.notesRef</tt> setting. +</p> +</dd> +<dt> +<em>GIT_NOTES_DISPLAY_REF</em> +</dt> +<dd> +<p> + Colon-delimited list of refs or globs indicating which refs, + in addition to the default from <tt>core.notesRef</tt> or + <em>GIT_NOTES_REF</em>, to read notes from when showing commit + messages. + This overrides the <tt>notes.displayRef</tt> setting. +</p> +<div class="para"><p>A warning will be issued for refs that do not exist, but a glob that +does not match any refs is silently ignored.</p></div> +</dd> +<dt> +<em>GIT_NOTES_REWRITE_MODE</em> +</dt> +<dd> +<p> + When copying notes during a rewrite, what to do if the target + commit already has a note. + Must be one of <tt>overwrite</tt>, <tt>concatenate</tt>, and <tt>ignore</tt>. + This overrides the <tt>core.rewriteMode</tt> setting. +</p> +</dd> +<dt> +<em>GIT_NOTES_REWRITE_REF</em> +</dt> +<dd> +<p> + When rewriting commits, which notes to copy from the original + to the rewritten commit. Must be a colon-delimited list of + refs or globs. +</p> +<div class="para"><p>If not set in the environment, the list of notes to copy depends +on the <tt>notes.rewrite.<command></tt> and <tt>notes.rewriteRef</tt> settings.</p></div> +</dd> +</dl></div> </div> <h2 id="_author">Author</h2> <div class="sectionbody"> @@ -537,7 +718,7 @@ </div> <div id="footer"> <div id="footer-text"> -Last updated 2010-04-24 02:56:02 UTC +Last updated 2010-06-13 19:56:35 UTC </div> </div> </body>
diff --git a/git-notes.txt b/git-notes.txt index 4e5113b..5540af5 100644 --- a/git-notes.txt +++ b/git-notes.txt
@@ -3,7 +3,7 @@ NAME ---- -git-notes - Add/inspect object notes +git-notes - Add or inspect object notes SYNOPSIS -------- @@ -15,29 +15,31 @@ 'git notes' edit [<object>] 'git notes' show [<object>] 'git notes' remove [<object>] -'git notes' prune +'git notes' prune [-n | -v] DESCRIPTION ----------- -This command allows you to add/remove notes to/from objects, without -changing the objects themselves. +Adds, removes, or reads notes attached to objects, without touching +the objects themselves. -A typical use of notes is to extend a commit message without having -to change the commit itself. Such commit notes can be shown by `git log` -along with the original commit message. To discern these notes from the +By default, notes are saved to and read from `refs/notes/commits`, but +this default can be overridden. See the OPTIONS, CONFIGURATION, and +ENVIRONMENT sections below. If this ref does not exist, it will be +quietly created when it is first needed to store a note. + +A typical use of notes is to supplement a commit message without +changing the commit itself. Notes can be shown by 'git log' along with +the original commit message. To distinguish these notes from the message stored in the commit object, the notes are indented like the message, after an unindented line saying "Notes (<refname>):" (or -"Notes:" for the default setting). +"Notes:" for `refs/notes/commits`). -This command always manipulates the notes specified in "core.notesRef" -(see linkgit:git-config[1]), which can be overridden by GIT_NOTES_REF. -To change which notes are shown by 'git-log', see the -"notes.displayRef" configuration. +To change which notes are shown by 'git log', see the +"notes.displayRef" configuration in linkgit:git-log[1]. -See the description of "notes.rewrite.<command>" in -linkgit:git-config[1] for a way of carrying your notes across commands -that rewrite commits. +See the "notes.rewrite.<command>" configuration for a way to carry +notes across commands that rewrite commits. SUBCOMMANDS @@ -101,15 +103,20 @@ Use the given note message (instead of prompting). If multiple `-m` options are given, their values are concatenated as separate paragraphs. + Lines starting with `#` and empty lines other than a + single line between paragraphs will be stripped out. -F <file>:: --file=<file>:: Take the note message from the given file. Use '-' to read the note message from the standard input. + Lines starting with `#` and empty lines other than a + single line between paragraphs will be stripped out. -C <object>:: --reuse-message=<object>:: - Reuse the note message from the given note object. + Take the note message from the given blob object (for + example, another note). -c <object>:: --reedit-message=<object>:: @@ -117,22 +124,151 @@ the user can further edit the note message. --ref <ref>:: - Manipulate the notes tree in <ref>. This overrides both - GIT_NOTES_REF and the "core.notesRef" configuration. The ref + Manipulate the notes tree in <ref>. This overrides + 'GIT_NOTES_REF' and the "core.notesRef" configuration. The ref is taken to be in `refs/notes/` if it is not qualified. +-n:: + Do not remove anything; just report the object names whose notes + would be removed. -NOTES ------ +-v:: + Report all object names whose notes are removed. + + +DISCUSSION +---------- + +Commit notes are blobs containing extra information about an object +(usually information to supplement a commit's message). These blobs +are taken from notes refs. A notes ref is usually a branch which +contains "files" whose paths are the object names for the objects +they describe, with some directory separators included for performance +reasons footnote:[Permitted pathnames have the form +'ab'`/`'cd'`/`'ef'`/`'...'`/`'abcdef...': a sequence of directory +names of two hexadecimal digits each followed by a filename with the +rest of the object ID.]. Every notes change creates a new commit at the specified notes ref. You can therefore inspect the history of the notes by invoking, e.g., -`git log -p notes/commits`. +`git log -p notes/commits`. Currently the commit message only records +which operation triggered the update, and the commit authorship is +determined according to the usual rules (see linkgit:git-commit[1]). +These details may change in the future. -Currently the commit message only records which operation triggered -the update, and the commit authorship is determined according to the -usual rules (see linkgit:git-commit[1]). These details may change in -the future. +It is also permitted for a notes ref to point directly to a tree +object, in which case the history of the notes can be read with +`git log -p -g <refname>`. + + +EXAMPLES +-------- + +You can use notes to add annotations with information that was not +available at the time a commit was written. + +------------ +$ git notes add -m 'Tested-by: Johannes Sixt <j6t@kdbg.org>' 72a144e2 +$ git show -s 72a144e +[...] + Signed-off-by: Junio C Hamano <gitster@pobox.com> + +Notes: + Tested-by: Johannes Sixt <j6t@kdbg.org> +------------ + +In principle, a note is a regular Git blob, and any kind of +(non-)format is accepted. You can binary-safely create notes from +arbitrary files using 'git hash-object': + +------------ +$ cc *.c +$ blob=$(git hash-object -w a.out) +$ git notes --ref=built add -C "$blob" HEAD +------------ + +Of course, it doesn't make much sense to display non-text-format notes +with 'git log', so if you use such notes, you'll probably need to write +some special-purpose tools to do something useful with them. + + +CONFIGURATION +------------- + +core.notesRef:: + Notes ref to read and manipulate instead of + `refs/notes/commits`. Must be an unabbreviated ref name. + This setting can be overridden through the environment and + command line. + +notes.displayRef:: + Which ref (or refs, if a glob or specified more than once), in + addition to the default set by `core.notesRef` or + 'GIT_NOTES_REF', to read notes from when showing commit + messages with the 'git log' family of commands. + This setting can be overridden on the command line or by the + 'GIT_NOTES_DISPLAY_REF' environment variable. + See linkgit:git-log[1]. + +notes.rewrite.<command>:: + When rewriting commits with <command> (currently `amend` or + `rebase`), if this variable is `false`, git will not copy + notes from the original to the rewritten commit. Defaults to + `true`. See also "`notes.rewriteRef`" below. ++ +This setting can be overridden by the 'GIT_NOTES_REWRITE_REF' +environment variable. + +notes.rewriteMode:: + When copying notes during a rewrite, what to do if the target + commit already has a note. Must be one of `overwrite`, + `concatenate`, and `ignore`. Defaults to `concatenate`. ++ +This setting can be overridden with the `GIT_NOTES_REWRITE_MODE` +environment variable. + +notes.rewriteRef:: + When copying notes during a rewrite, specifies the (fully + qualified) ref whose notes should be copied. May be a glob, + in which case notes in all matching refs will be copied. You + may also specify this configuration several times. ++ +Does not have a default value; you must configure this variable to +enable note rewriting. ++ +Can be overridden with the 'GIT_NOTES_REWRITE_REF' environment variable. + + +ENVIRONMENT +----------- + +'GIT_NOTES_REF':: + Which ref to manipulate notes from, instead of `refs/notes/commits`. + This overrides the `core.notesRef` setting. + +'GIT_NOTES_DISPLAY_REF':: + Colon-delimited list of refs or globs indicating which refs, + in addition to the default from `core.notesRef` or + 'GIT_NOTES_REF', to read notes from when showing commit + messages. + This overrides the `notes.displayRef` setting. ++ +A warning will be issued for refs that do not exist, but a glob that +does not match any refs is silently ignored. + +'GIT_NOTES_REWRITE_MODE':: + When copying notes during a rewrite, what to do if the target + commit already has a note. + Must be one of `overwrite`, `concatenate`, and `ignore`. + This overrides the `core.rewriteMode` setting. + +'GIT_NOTES_REWRITE_REF':: + When rewriting commits, which notes to copy from the original + to the rewritten commit. Must be a colon-delimited list of + refs or globs. ++ +If not set in the environment, the list of notes to copy depends +on the `notes.rewrite.<command>` and `notes.rewriteRef` settings. Author
diff --git a/git-rev-list.html b/git-rev-list.html index e740b98..89cd9b4 100644 --- a/git-rev-list.html +++ b/git-rev-list.html
@@ -1365,7 +1365,12 @@ have limited your view of history: for example, if you are only interested in changes related to a certain directory or file.</p></div> -<div class="para"><p>Here are some additional details for each format:</p></div> +<div class="para"><p>There are several built-in formats, and you can define +additional formats by setting a pretty.<name> +config option to either another format name, or a +<em>format:</em> string, as described below (see +<a href="git-config.html">git-config(1)</a>). Here are the details of the +built-in formats:</p></div> <div class="ilist"><ul> <li> <p> @@ -1787,7 +1792,7 @@ </div> <div id="footer"> <div id="footer-text"> -Last updated 2010-06-02 23:32:09 UTC +Last updated 2010-06-13 19:56:35 UTC </div> </div> </body>
diff --git a/git-show.html b/git-show.html index f1b6fb6..a037a0f 100644 --- a/git-show.html +++ b/git-show.html
@@ -441,7 +441,12 @@ have limited your view of history: for example, if you are only interested in changes related to a certain directory or file.</p></div> -<div class="para"><p>Here are some additional details for each format:</p></div> +<div class="para"><p>There are several built-in formats, and you can define +additional formats by setting a pretty.<name> +config option to either another format name, or a +<em>format:</em> string, as described below (see +<a href="git-config.html">git-config(1)</a>). Here are the details of the +built-in formats:</p></div> <div class="ilist"><ul> <li> <p> @@ -980,7 +985,7 @@ </div> <div id="footer"> <div id="footer-text"> -Last updated 2010-06-02 23:32:09 UTC +Last updated 2010-06-13 19:56:36 UTC </div> </div> </body>
diff --git a/git-submodule.html b/git-submodule.html index 0b0aca2..23d8f3e 100644 --- a/git-submodule.html +++ b/git-submodule.html
@@ -475,10 +475,12 @@ <dd> <p> Evaluates an arbitrary shell command in each checked out submodule. - The command has access to the variables $name, $path and $sha1: + The command has access to the variables $name, $path, $sha1 and + $toplevel: $name is the name of the relevant submodule section in .gitmodules, $path is the name of the submodule directory relative to the - superproject, and $sha1 is the commit as recorded in the superproject. + superproject, $sha1 is the commit as recorded in the superproject, + and $toplevel is the absolute path to the top-level of the superproject. Any submodules defined in the superproject but not checked out are ignored by this command. Unless given --quiet, foreach prints the name of each submodule before evaluating the command. @@ -661,7 +663,7 @@ </div> <div id="footer"> <div id="footer-text"> -Last updated 2010-04-24 02:56:10 UTC +Last updated 2010-06-13 19:56:36 UTC </div> </div> </body>
diff --git a/git-submodule.txt b/git-submodule.txt index 2502531..cdabfd2 100644 --- a/git-submodule.txt +++ b/git-submodule.txt
@@ -145,10 +145,12 @@ foreach:: Evaluates an arbitrary shell command in each checked out submodule. - The command has access to the variables $name, $path and $sha1: + The command has access to the variables $name, $path, $sha1 and + $toplevel: $name is the name of the relevant submodule section in .gitmodules, $path is the name of the submodule directory relative to the - superproject, and $sha1 is the commit as recorded in the superproject. + superproject, $sha1 is the commit as recorded in the superproject, + and $toplevel is the absolute path to the top-level of the superproject. Any submodules defined in the superproject but not checked out are ignored by this command. Unless given --quiet, foreach prints the name of each submodule before evaluating the command.
diff --git a/git-update-index.html b/git-update-index.html index 6d7f30f..56c4778 100644 --- a/git-update-index.html +++ b/git-update-index.html
@@ -460,8 +460,6 @@ <div class="para"><p>This option can be also used as a coarse file-level mechanism to ignore uncommitted changes in tracked files (akin to what <tt>.gitignore</tt> does for untracked files). -You should remember that an explicit <em>git add</em> operation will -still cause the file to be refreshed from the working tree. Git will fail (gracefully) in case it needs to modify this file in the index e.g. when merging in a commit; thus, in case the assumed-untracked file is changed upstream, @@ -839,7 +837,7 @@ </div> <div id="footer"> <div id="footer-text"> -Last updated 2010-04-24 02:56:11 UTC +Last updated 2010-06-13 19:56:37 UTC </div> </div> </body>
diff --git a/git-update-index.txt b/git-update-index.txt index 68dc187..765d4b3 100644 --- a/git-update-index.txt +++ b/git-update-index.txt
@@ -93,8 +93,6 @@ This option can be also used as a coarse file-level mechanism to ignore uncommitted changes in tracked files (akin to what `.gitignore` does for untracked files). -You should remember that an explicit 'git add' operation will -still cause the file to be refreshed from the working tree. Git will fail (gracefully) in case it needs to modify this file in the index e.g. when merging in a commit; thus, in case the assumed-untracked file is changed upstream,
diff --git a/git-whatchanged.html b/git-whatchanged.html index 245ff5b..0f96644 100644 --- a/git-whatchanged.html +++ b/git-whatchanged.html
@@ -473,7 +473,12 @@ have limited your view of history: for example, if you are only interested in changes related to a certain directory or file.</p></div> -<div class="para"><p>Here are some additional details for each format:</p></div> +<div class="para"><p>There are several built-in formats, and you can define +additional formats by setting a pretty.<name> +config option to either another format name, or a +<em>format:</em> string, as described below (see +<a href="git-config.html">git-config(1)</a>). Here are the details of the +built-in formats:</p></div> <div class="ilist"><ul> <li> <p> @@ -919,7 +924,7 @@ </div> <div id="footer"> <div id="footer-text"> -Last updated 2010-06-02 23:32:09 UTC +Last updated 2010-06-13 19:56:37 UTC </div> </div> </body>
diff --git a/git.html b/git.html index 3947940..7708de5 100644 --- a/git.html +++ b/git.html
@@ -685,7 +685,7 @@ </dt> <dd> <p> - Add/inspect object notes. + Add or inspect object notes. </p> </dd> <dt> @@ -2108,7 +2108,7 @@ </div> <div id="footer"> <div id="footer-text"> -Last updated 2010-05-21 14:57:19 UTC +Last updated 2010-06-13 19:56:37 UTC </div> </div> </body>
diff --git a/gitignore.html b/gitignore.html index 7e5ba9a..8d5685d 100644 --- a/gitignore.html +++ b/gitignore.html
@@ -419,7 +419,9 @@ <p> If the pattern does not contain a slash <em>/</em>, git treats it as a shell glob pattern and checks for a match against the - pathname without leading directories. + pathname relative to the location of the <tt>.gitignore</tt> file + (relative to the toplevel of the work tree if not from a + <tt>.gitignore</tt> file). </p> </li> <li> @@ -428,10 +430,15 @@ for consumption by fnmatch(3) with the FNM_PATHNAME flag: wildcards in the pattern will not match a / in the pathname. For example, "Documentation/*.html" matches - "Documentation/git.html" but not - "Documentation/ppc/ppc.html". A leading slash matches the - beginning of the pathname; for example, "/*.c" matches - "cat-file.c" but not "mozilla-sha1/sha1.c". + "Documentation/git.html" but not "Documentation/ppc/ppc.html" + or "tools/perf/Documentation/perf.html". +</p> +</li> +<li> +<p> +A leading slash matches the beginning of the pathname. + For example, "/*.c" matches "cat-file.c" but not + "mozilla-sha1/sha1.c". </p> </li> </ul></div> @@ -486,7 +493,7 @@ </div> <div id="footer"> <div id="footer-text"> -Last updated 2010-04-24 02:56:13 UTC +Last updated 2010-06-13 19:56:37 UTC </div> </div> </body>
diff --git a/gitignore.txt b/gitignore.txt index 98c459d..e10fa88 100644 --- a/gitignore.txt +++ b/gitignore.txt
@@ -83,16 +83,20 @@ - If the pattern does not contain a slash '/', git treats it as a shell glob pattern and checks for a match against the - pathname without leading directories. + pathname relative to the location of the `.gitignore` file + (relative to the toplevel of the work tree if not from a + `.gitignore` file). - Otherwise, git treats the pattern as a shell glob suitable for consumption by fnmatch(3) with the FNM_PATHNAME flag: wildcards in the pattern will not match a / in the pathname. For example, "Documentation/\*.html" matches - "Documentation/git.html" but not - "Documentation/ppc/ppc.html". A leading slash matches the - beginning of the pathname; for example, "/*.c" matches - "cat-file.c" but not "mozilla-sha1/sha1.c". + "Documentation/git.html" but not "Documentation/ppc/ppc.html" + or "tools/perf/Documentation/perf.html". + + - A leading slash matches the beginning of the pathname. + For example, "/*.c" matches "cat-file.c" but not + "mozilla-sha1/sha1.c". An example:
diff --git a/pretty-formats.txt b/pretty-formats.txt index b055a67..8c68ce9 100644 --- a/pretty-formats.txt +++ b/pretty-formats.txt
@@ -11,7 +11,12 @@ only interested in changes related to a certain directory or file. -Here are some additional details for each format: +There are several built-in formats, and you can define +additional formats by setting a pretty.<name> +config option to either another format name, or a +'format:' string, as described below (see +linkgit:git-config[1]). Here are the details of the +built-in formats: * 'oneline'
